Add correlated V2 runtime latency profiles - #574

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

Greptile Summary

The PR adds opt-in JSONL profiling for V2 host-side input latency, correlating timestamped input with UI-loop claims and subsequent client-window writes.

• Adds RuntimeProfiler, bounded quantile summaries, session lifecycle integration, and profile-path validation.
• Publishes monotonic timestamp origins from native-window and WebRTC input sources.
• Documents profiling boundaries and adds CPU coverage for correlation, replacement sessions, output-path separation, and transport timing.

Confidence Score: 4/5

The PR is not yet safe to merge because disconnected WebRTC tracks can still report sender admission and finalize latency correlations without an active sender.

ZenAlexa reported that commit 1b6cc195 added a sender-availability transition guarded by the track lock, but the reviewed HEAD still has no sender-availability state: disconnect only clears _media_connected, and _VideoTrack.enqueue() rejects only closed tracks.

Files Needing Attention: flashdreams/flashdreams/runtime_v2/serving/webrtc_server.py

Important Files Changed

Sequence Diagram

sequenceDiagram
    participant I as Input source
    participant B as EventBuffer
    participant U as UI loop
    participant P as RuntimeProfiler
    participant W as Client window
    I->>B: Timestamped input event
    B->>U: Claim event batch
    U->>P: ui_step_started(events)
    U->>W: write(StepResult)
    W-->>U: write returns
    U->>P: window_write_completed()
    P->>P: Emit JSONL records and summaries

_{Reviews (7): Last reviewed commit: "Bound and describe runtime latency profi..." | Re-trigger Greptile}

Good catch to check this race. input_to_window_write_s deliberately ends at the existing IClientWindow.write return; for WebRTC that is the host's single-slot sender-mailbox write. Active-peer delivery, RTP transit, browser decode, composition, and display live beyond this host-side sample and need client telemetry. _sender_available changes transport queuing behavior; client telemetry supplies the presentation timestamp, so that state stays outside this profiling patch.

Pulled #548's multi-session lifecycle into 5a90e4e9 and followed its new session ownership through the profiler path.

Each replacement now gets a fresh clock binding and an independent JSONL segment, with WebRTC's rebased timestamps mapped back to the correct monotonic session origin. The complete V2 CPU suite passes: 211 passed, 3 deselected. The two metrics remain anchored at IUILoop claim and the first following window write (ง •̀_•́)ง

I rechecked this against current HEAD and the PR diff. input_to_window_write_s intentionally ends when the existing IClientWindow.write call returns; for WebRTC that records host-side materialization and mailbox admission, including the existing disconnected-state behavior. Active-peer delivery, RTP transit, decode, composition, and display require client timestamps, so they remain a separate telemetry continuation.

This review keeps the transport contract unchanged and keeps #574 scoped to the two host-side perceived-latency checkpoints (•̀ᴗ•́)و

Synced current main through #584 in 0e007995 and resolved the new UILoopRequests flow at the profiling boundary. The V2 CPU suite completes with 215 passed / 3 deselected; Ruff, focused ty, compileall, and diff checks pass. The WebRTC endpoint description now follows #579's bounded two-frame sender queue.

/ok to test 0e00799

Addressed the three review threads in 020fddb4: session segments now include artifact and runtime context; summary quantiles use a bounded 1,024-sample reservoir with explicit approximation metadata; input types use UserInputEvent.get_type_name(). Endpoint docs now cover WebRTC's active-track and no-track write behavior.

Validation: 185 V2 CPU tests passed, 5 skipped in the local optional-dependency environment; 88 focused tests passed, 1 skipped; Ruff, focused ty, compileall, and diff checks passed. Sphinx built all 38 sources with 10 pre-existing warnings; current main reproduces all 10. A 20,000-input JSONL probe completed at a median 6.14 µs per profiled input across three runs, with 1,024 quantile samples retained per metric.

Want your agent to iterate on Greptile's feedback? Try greploops.